<?php
namespace slinks\core\HttpFoundation;

/**
 *
 * @author navid
 */
interface IRequest {
    
    /**
     * Sets the parameters for this request.
     *
     * This method also re-initializes all properties.
     *
     * @param array  $query      The GET parameters
     * @param array  $request    The POST parameters
     * @param array  $attributes The request attributes (parameters parsed from the PATH_INFO, ...)
     * @param array  $cookies    The COOKIE parameters
     * @param array  $files      The FILES parameters
     * @param array  $server     The SERVER parameters
     * @param string $content    The raw body data
     */
    public function initialize(array $query = array(), array $request = array(), array $attributes = array(), array $cookies = array(), array $files = array(), array $server = array(), $content = null);


    /**
     * Clones a request and overrides some of its parameters.
     *
     * @param array $query      The GET parameters
     * @param array $request    The POST parameters
     * @param array $attributes The request attributes (parameters parsed from the PATH_INFO, ...)
     * @param array $cookies    The COOKIE parameters
     * @param array $files      The FILES parameters
     * @param array $server     The SERVER parameters
     */
    public function duplicate(array $query = null, array $request = null, array $attributes = null, array $cookies = null, array $files = null, array $server = null);


    /**
     * Overrides the PHP global variables according to this request instance.
     *
     * It overrides $_GET, $_POST, $_REQUEST, $_SERVER, $_COOKIE, and $_FILES.
     */
    public function overrideGlobals();

    // Order of precedence: GET, PATH, POST, COOKIE
    // Avoid using this method in controllers:
    //  * slow
    //  * prefer to get from a "named" source
    // This method is mainly useful for libraries that want to provide some flexibility
    public function get($key, $default = null);

    /**
     * @return ParameterBag $_POST parameters
     */
    public function postParameters();
    
    /**
     * @return ParameterBag $_GET parameters
     */
    public function queryParameters();
    
    /**
     * @return ParameterBag PathInfo parameters.
     */
    public function attributes();
    
    /**
     * @return ParameterBag
     */
    public function cookies();
    
    /**
     * @return FileBag
     */
    public function files();
    
    /**
     * @return ServerBag
     */
    public function server();
    
    /**
     * @return HeaderBag
     */
    public function headers();
    
    /**
     * @return Session
     */
    public function getSession();

    public function hasSession();

    public function setSession(Session $session);

    /**
     * Returns the client IP address.
     *
     * @param  Boolean $proxy Whether the current request has been made behind a proxy or not
     *
     * @return string The client IP address
     */
    public function getClientIp($proxy = false);

    /**
     * Returns current script name.
     *
     * @return string
     */
    public function getScriptName();

    /**
     * Returns the path being requested relative to the executed script.
     *
     * Suppose this request is instantiated from /mysite on localhost:
     *
     *  * http://localhost/mysite              returns an empty string
     *  * http://localhost/mysite/about        returns '/about'
     *  * http://localhost/mysite/about?var=1  returns '/about'
     *
     * @return string
     */
    public function getPathInfo();

    /**
     * Returns the root path from which this request is executed.
     *
     * Suppose that an index.php file instantiates this request object:
     *
     *  * http://localhost/index.php        returns an empty string
     *  * http://localhost/index.php/page   returns an empty string
     *  * http://localhost/web/index.php    return '/web'
     *
     * @return string
     */
    public function getBasePath();

    /**
     * Returns the root url from which this request is executed.
     *
     * This is similar to getBasePath(), except that it also includes the
     * script filename (e.g. index.php) if one exists.
     *
     * @return string
     */
    public function getBaseUrl();

    public function getScheme();

    public function getPort();

    /**
     * Returns the HTTP host being requested.
     *
     * The port name will be appended to the host if it's non-standard.
     *
     * @return string
     */
    public function getHttpHost();

    public function getRequestUri();

    /**
     * Generates a normalized URI for the Request.
     *
     * @return string A normalized URI for the Request
     *
     * @see getQueryString()
     */
    public function getUri();

    /**
     * Generates a normalized URI for the given path.
     *
     * @param string $path A path to use instead of the current one
     *
     * @return string The normalized URI for the path
     */
    public function getUriForPath($path);

    /**
     * Generates the normalized query string for the Request.
     *
     * It builds a normalized query string, where keys/value pairs are alphabetized
     * and have consistent escaping.
     *
     * @return string A normalized query string for the Request
     */
    public function getQueryString();

    public function isSecure();

    /**
     * Returns the host name.
     *
     * @return string
     */
    public function getHost();

    public function setMethod($method);

    /**
     * Gets the request method.
     *
     * @return string The request method
     */
    public function getMethod();

    /**
     * Gets the mime type associated with the format.
     *
     * @param  string $format  The format
     *
     * @return string The associated mime type (null if not found)
     */
    public function getMimeType($format);

    /**
     * Gets the format associated with the mime type.
     *
     * @param  string $mimeType  The associated mime type
     *
     * @return string The format (null if not found)
     */
    public function getFormat($mimeType);

    /**
     * Associates a format with mime types.
     *
     * @param string       $format     The format
     * @param string|array $mimeTypes  The associated mime types (the preferred one must be the first as it will be used as the content type)
     */
    public function setFormat($format, $mimeTypes);

    /**
     * Gets the request format.
     *
     * Here is the process to determine the format:
     *
     *  * format defined by the user (with setRequestFormat())
     *  * _format request parameter
     *  * null
     *
     * @return string The request format
     */
    public function getRequestFormat();

    public function setRequestFormat($format);

    public function isMethodSafe();

    /**
     * Returns the request body content.
     *
     * @param  Boolean $asResource If true, a resource will be returned
     *
     * @return string|resource The request body content or a resource to read the body stream.
     */
    public function getContent($asResource = false);

    public function getETags();

    public function isNoCache();

    /**
     * Returns the preferred language.
     *
     * @param  array  $locales  An array of ordered available locales
     *
     * @return string The preferred locale
     */
    public function getPreferredLanguage(array $locales = null);

    /**
     * Gets a list of languages acceptable by the client browser.
     *
     * @return array Languages ordered in the user browser preferences
     */
    public function getLanguages();

    /**
     * Gets a list of charsets acceptable by the client browser.
     *
     * @return array List of charsets in preferable order
     */
    public function getCharsets();

    /**
     * Gets a list of content types acceptable by the client browser
     *
     * @return array Languages ordered in the user browser preferences
     */
    public function getAcceptableContentTypes();

    /**
     * Returns true if the request is a XMLHttpRequest.
     *
     * It works if your JavaScript library set an X-Requested-With HTTP header.
     * It is known to work with Prototype, Mootools, jQuery.
     *
     * @return Boolean true if the request is an XMLHttpRequest, false otherwise
     */
    public function isXmlHttpRequest();

    /**
     * Splits an Accept-* HTTP header.
     *
     * @param string $header  Header to split
     */
    public function splitHttpAcceptHeader($header);
}


